Gulam

Guläm is a shell (i.e., a command line interpreter) for AtariST computers. It contains some 60+ built-in commands, provides file name completion a la TENEX, has history, alias and rehash facilities, and integrates the shell with microEmacs easing the editing of commands being issued. Among the built-in commands are

In common usage, it resembles csh of Unix 4.xBSD; Guläm’s control structures, lexical conventions and other details are, however, quite different from csh. While I have borrowed ideas from other shells (such as Korn shell), I made no heroic attempts to be compatible with any. Where possible, I have tried to make Guläm less ‘surprising’ in what it does.

The word Guläm is pronounced as Gulaam in Hindi/Urdu, and means an obedient servant.

Guläm is a free program; you are encouraged to give it to others, but at no cost. However, the source is copyrighted (i.e., it is not in the public domain) and will be part of a book on systems programming I am writing. The source is available on request, with the usual provisos regarding material in manuscript form. This manual is written in the TeXinfo format (the GNU documentation format); a laser-printed TeX-typeset copy of this 40-page manual is also available at cost ($2.00).

I am advised to include a disclaimer because there are unreasonable people out there.

“I make no warranty with respect to this manual, or the program it describes, and disclaim any implied/explicit suggestions of usefulness for any particular purpose. Use this program only if you are willing to assume all risks, and damages, if any, arising as a result, even if it is caused by negligence or other fault.”

The first release of this program did contain bugs. The present beta-version (dated Sept 1987) is a result of fixing 15 bugs, 9 internal code improvements (about 180 lines of rewriting), 9 user-visible improvements. I am sure this version too has bugs, and undesirable features. Users are encouraged to tell me both good and bad things about this program.

Many thanks to: Jwahar R. Bammi for help in every aspect during the writing of the shell and this manual, and demanding that Guläm be a ‘reasonably full fledged’ shell; David Conroy for writing a ‘small is beautiful’ microEmacs; Henry Spencer for the regexp(3) package that is now built into Guläm; AtariST for its value to price ratio. The program was developed using Megamax and Mark Williams C compilers. It now uses my own malloc.c.

Comments on the Present Implementation

I find the present implementation eminently useable, and indeed use it all the time, in preference to other shells.

Here are some features that I (still) find unsatisfactory. Control structures are quite ad-hoc, and incomplete. I had a tough time in decreeing that the typical ‘+-*/()[]{}’ are not delimiters; but that decision made Guläm smaller.

Here is a list (complete?) of things new and/or diffrent from the alpha-version.

General Usage

The syntactic details of individual commands, and the specific rules that are followed in evaluating them are given later. This section is an overview of how the integration of ue with a shell is used.

The moment you enter Guläm, you are in a ue-buffer called mini. Thus, all the typical ue text-editing functions are available, except commands such as Visit-file, Switch-to-buffer, etc. The RETURN key causes the entire line (on which the return is typed) to be evaluated. The output, if any, of the command you issued appears on the screen but does not enter any ue-buffer. The built-in command ue (without any arguments) takes you into the special ue-buffer named guläm; the output of (built-in) commands issued while you are in guläm does enter that buffer, which can be freely edited. The command ue filename will read-in each of the named files into their ue-buffers. From within ue, you can Switch-to-Gulam-buffer (whose default binding is ESC-g).

To conserve/manage memory, we release all ue buffers when ue is exited in the usual way (i.e., UNDO, or X-C); exiting temporarily via the Z does not release memory. Issuing a substantial number of commands through the mini buffer, without entering ue in between, will accumulate all the commands (but not their output) in the mini buffer, and soon there will be a memory shortage. To prevent this, enter and exit ue once in a while, or delete (using D, or Delete) characters in the mini buffer.

Lexical Conventions

All input to Guläm is case-sensitive; on the other hand, TOS file names are case-independent.

The evaluation of the command line begins by dividing it into words and subwords. The word-delimiters are:

space   tab     return  line-feed       (the so-called white chars)
single-quote    double-quote
semicolon       vertical-bar

date  01-22-87-22:08:34  #sets the TOS and ikbd date and time
alias cl 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .; linkmm l.lnk'
if    {$x + $y ==23 }
if    { -e $1.c }

/date/01-22-87-22:08:34/#sets/the/TOS/and/ikbd/date/and/time/
/alias/cl/'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .; linkmm l.lnk'/
/if/{$x/+/$y/==23/}/
/if/{/-e/$1.c/}/

Comments begin with a word whose first char is #, and end at the end of line. A # embedded in the middle of a word does not begin a comment.

Outline of Command Processing

The command line is string pre-processed as described below before invoking it as a command.

Batch Files

A batch file, also called a shell file, is a text file containing Guläm commands, both internal and external. Such files must have the extension .g for them to be recognized as commands. See the section on gulam.g for an example shell file.

In processing these files Guläm uses ue buffers. So, if you have ue as a command in a batch file, and then exit ue with either UNDO or X-C, all the buffers (including the one holding the batch file) will be released, and Guläm will surely crash. So, do NOT include ue as a command in a shell file.

Buffers: Gulam, Mini and Regular Buffers

Once you invoke Guläm, you are always in one of the microEmacs (uE) buffers which are reservoirs of text. In this program, a typical line-oriented command shell is integrated with microEmacs. This necessitated two special kinds of buffers, named guläm and mini, along with the regular buffers.

Right after you invoke Guläm, you are in mini, and each line you type is taken as a Guläm command, and executed. Any output produced by such a command is displayed on the screen but not entered into any microEmacs buffer. Should you desire to capture such output into a buffer, enter the guläm buffer by typing ue without any arguments. If you are editing in a regular buffer elsewhere in microEmacs, pressing ESC-g (see uekb below for switch-to-Gulam-buffer) will get you into guläm.

While you are in Guläm, the RETURN key behaves as it does in mini. All command input, including giving the names of buffers within ue, takes place in mini. The window for this buffer is always at the bottom of screen, and usually only one-line high. (Some of you may want to experiment with X-Z and X-z.) You enter the mini either because (A) you are outside the normal microEmacs, or (B) a command such as Switch-to-buffer wants to read your input. The mini is like any other buffer except for the bindings of a few keys, and the disallowing of ue functions that change/switch buffers/windows/files. One of these exceptional keys (in mini) is the RETURN key: it will submit the entire line – even if the cursor was somewhere in the middle of the line– to the shell (case A), or to such ue commands as Visit-File (case B). Until you press RETURN, you can edit not only that line but others in mini just as you would in regular buffers.

Note that unless you occasionally exit microEmacs with X-C or UNDO, both guläm and mini buffers will keep growing, and you may run out of memory.

Command Line Editing

Full microEmacs editing is available while typing the command. Thus, you can transopse chars by T, and go to the beginning of the line by A, and Yank in a perviously deleted word, etc.

In addition to these, there are three convenience features. After typing the first few chars of a file name, if you press the key marked INSERT, Guläm will attempt to complete the file name; pressing CLR/HOME will show all possible completions. Secondly, if you type !n and then press INSERT, you will see that the history-expanded result is brought into the buffer, which can then be further edited if necessary. Thirdly, pressing the DOWNARROW key will cycle you through the previous commands.

Invoking Gulam

Guläm can be used in four ways. Two of these four use TOS variable named _shell_p (at 0x04f6L). This (supposedly) contains a pointer to a routine that takes a string as an argument and executes it as a shell command. Guläm has slightly extented this. *_shell_p, as set by Guläm, points the bottom of a (jump) table, which currently is:

        .long   0x86420135        / our magic number
        jmp     getlineviaue_
togu_:  jmp     callgulam_

Thus, *((long *) 0x04f6L) == address of togu_. Before invoking either routine, it always is a good idea to check if the magic number is present. Let mp = *((long *) 0x04f6L) - 12L. Then, *mp better be 0x86420135.

gu 'ls -l' 'echo hello' is similar to typing the two commands to the shell in interactive mode.

gu 'pwd' -c scrpt a b c d does pwd, and then invokes the (presumably valid) Guläm shell script named scrpt.g with a b c d as the script files arguments. Following the -c must be the name of a batch file.

Glossary

Builtin Commands

A command executed directly by the shell is called a built-in command. The 62 built-in commands of Guläm are:

alias    dm       endwhile help     more     printenv set      ue 
cat      dirc     exit     history  mson     pushd    setenv   unalias 
cd       dirs     fg       if       msoff    pwd      source   unset 
chmod    echo     fgrep    kb       mv       rehash   sx       unsetenv 
copy     egrep    foreach  lpr      peekw    ren      te       which 
cp       ef       format   ls       pokew    rm       teexit   while 
date     endfor   gem      mem      popd     rmdir    time     
df       endif    grep     mkdir    print    rx       touch

alias

The alias built-in command works almost like a shell file but one that is stored in the internal data structures of Guläm. It often just specifies a shorter or different name for a command.

alias cc c:\megamax\mmcc.ttp    #1
unalias cc                      #2
alias cl 'mmcc e:\gulam\$1.c; cp e:\gulam\$1.o .; linkmm l.lnk' #3
alias r  'echo $1.c $1.o; r'    #4
alias                           #5
alias g 'echo $3 $1'            #6
alias cg 'f:\cc.ttp -c -V -Ie:\gulam -DMWC e:\gulam\$1.c' #7

Alias without args (see #5) lists all the aliases that are currently defined. The command unalias (see 2) removes the def of an alias. Line 4 shows a recursive definition; try it out! If we invoke g as in g a b c d e f this is equivalent to echo c a d e f; i.e., all arguments above the highest that was used in a $-substitution are appended to the resulting command string before executing it.

cat

This command ‘catenates’ files to the standard output (normally screen). By redirecting output, you can concatenate several files into a combined file.

cat f1 f2 >f3	# f3 will now equal f1 followed by f2
cat f1 > prn:	# print the file f1 as is; see also print and lpr
cat f1		# show it on the screen; use ^S/^Q to stop/go

The cd command changes the current working directory; it also sets the shell variable named cwd, the environment variable named CWD. If cd was given noarguments, it is equivalent to cd $home.

chmod

chmod [+-w] filenames

chmod changes the read/write attributes of the files: +w makes them read-write, and -w makes them read-only.

cp filenames target-dir
cp filename1 filename2

Copies files. In the first form, any number of files may be copied into the destination directory; files in the target dir will have their original names. In the second form, only one file is copied, and the new one will be named filename2.

cp fnm fnm    # will exit with status -1 
cp -r d1 dir2     # if d1 is a directory, this command will
              # create a dir named d1 in dir2, and copies
              # all the files in d1 to to dir2\d1

In the second example above, if -r option is omitted, cp will ignore any directory names in the list of source files. Use the -r option with caution. E.g.,

cp -r d1  d1\d2 # is dangerous

will, assuming that d1\d2 is a directory, copy/create subtree d1 inside d2. But, the problem is that d1 will keep growing as a result until of course there is no more room on the target disk!

There is a +t option that gives the created target files the time and date of the source files. If you care about this, you may want to set up an alias as in:

$cwd and $CWD

The shell variable named cwd (and env var named CWD) holds the full path name of the current working directory.

date

The date command, without arguments, prints the current date and time. With arguments, it sets the date and time.

date 01-22-87-22:08:34

will set the date to Jan 22, 87 and time to 10:08:34 pm. Instead of hyphen, and colon, other delimiters can be used, as long as the whole argument of date is still one word.

dir cache dirc

To help do the Tenex file name completion efficiently, there is a cache of contents of directories. dirc shows the names of these dirs, and how many bytes are used by their contents. Unless you did a set dir_cache 1, or you executed commands that only examine the file system the dirc has nothing to show since the cache is flushed at the end of each command. Try Guläm with dir_cache set to 1. Note however that this cache is updated only by commands that change the contents of a directory (such as rm, cp). A rather annoying result is that even after you change the diskette in a drive, you may see the directory contents of the previous diskette listed. An UNDO, dirc -, rm with/without arguments will explicitly flush the cache.

dirs

Guläm has an internal stack of directories whose content is printed by the dirs command. The built-in commands pushd, and popd are the only others that operate on this stack.

Dollar-substitutions

The subword $x in a command is substituted by the value of it. If x is the name of a shell var, or an environment var, then $x is the value of that variable. If x is an unsigned number, it stands for the x-th argument; thus, $0 usually gives the command name. $* stands for the text of the entire command; $- stands for words $1 to dollar-last; $< stands for the on-demand input given by the user.

Dotg.g

echo

echo c:\mwc\...	# all the fnms in the dir tree rooted at c:\mwc will be echoed

egrep

endif

endfor

$env style

This shell var controls the format of the environment string supplied to the external command invoked through Guläm.

set env_style bm # to get a style of env string a la Beckmeyer
set env_style mw # Mark Williams
set env_style gu # the "normal" style, a la Unix

exit

Expressions

An atomic exp is either a number, a filename, a file predicate, a { exp }, or ! atomic exp.

A file predicate on a file name fnm is of the form

-c
fnm

where c is in {e, f, d, h, v, m}. These letters stand for exists, is-a-regular-file, is-a-dir, is-a-hidden-file, is-a-volume-label, and is-an-archived-file. A filepred yields 1 if it is true, 0 otherwise.

An arithmetic expression is constructed using the operators +-/%*. All these are of equal precedence and evaluated left-to-right; thus, 2 + 4 / 2 is equal to 3. However, the braces raise the precedence of the ops within them; thus, 2 + { 6 / 2} is equal to 5. An exp with no operators, i.e., an atom, is a special case because we want the string form of the atom (e.g., as for blah in set s blah). A non-numeric string yields 0 as its numeric value in an arith exp.

A relational expression is of the form

arithexp relation
arithexp

, where relation is any one of <=, <, ==, !=, >, or >=. Such a relation yields a 1 if it holds, 0 otherwise. (Relational operators among strings are not implemented yet.) You may combine expressions using the boolean operators && and || (which are not, for now, short-circuit evaluated).

fg is part of the simulation of what we were used to doing on Unix with GNU-Emacs: get out of it by stopping GNU (Z in ue/Gulam), do a few shell commands and get back in by fg (works the same in ue/Gulam).

File Names

There are many conveniences in Guläm that relate to specifying filenames. It can complete a file name given its first few characters. (Tenex is widely considered to be the first OS to implement this.) Type the first few characters, and then press the key marked INSERT (or CLR/HOME), while you are in mini. If you are in buffer guläm, use ESC ESC (2 escapes).

The canonical form of the full path name of a file begins with a letter designating the disk drive, followed by a colon, a back-slash separated list of identifiers. All but the last of these identifiers must be a directory name. In the non-standard form, you may also use a dot ‘.’, and dot-dot ‘..’ in place of the identifiers in appropriate contexts. Whenever Guläm completes your filenames, it will produce the standard form full path names.

Guläm will standardize, in three situations, non-standard form of a ‘path’, as shown in the example below. These situations are:

e:\gulam\a:\lex.c is standarddized to a:\lex.c e:\gulam\\src\util.c is standarddized to c:\src\util.c e:\gulam\~\ex.o is standarddized to d:\bin\ex.c

assuming that the current drive was c:\, and home was d:\bin. This is especially nice inside ue when visiting other files.

Words, as given by the you, that contain meta characters (which are *?|()[]) or the string ... are expanded. In general, one such word produces a list of file names. These file name regular expressions (fnmre) are like regular expressions (re), but have different semantics. Occurrences of an fnmre, outside of strings, are replaced by the sorted blank-separated list of file names matching the fnmre. An fnmre differs from re in (1) ‘.’ stands for itself; (2) ‘*’ is matches zero or more arbitrary characters. Question mark matches any one character. ‘[a-g]’ matches any one letter in a, b, ..., g. ‘[zen]’ matches one of z, e, or n. Parentheses serve to group expressions. An exp ‘g*’ matches file names that begin with a ‘g’; ‘*.c’ matches those ending in ‘.c’

The 3 dots, as in c:\tex\..., stand for all the names of the files in the subtree at c:\tex. If c:\tex has subdirectories, and so on, all their names and files they contain are included. Thus, echo e:\...\*.c will show all the .c files in all the directories on drive e. Remember that ... expansion causes many directories to be visited. This is not only time consuming, but also seems to trigger the Atari TOS’s 40 folder bug after a few such operations. (In my tests, I never lost a file as a result. Nor can I tell precisely when and in what form this shows up. Most frequent indication was that cd to an existing drive would fail.)

Flags

Most commands (built-in or external) take flags to alter the behavior of the command in a minor way. The convention made popular by Unix shells is adopted here for Guläm’s built-ins: a flag is of the form -c, or +c, where c stands for one character. The option -i, which interrogates you for each of the operand of the command before executing it, is provided on most commands.

foreach

The foreach command is used in shell scripts (but not at the terminal) to specify repetition of a sequence of commands while the value of a certain shell variable ranges through a specified list. The foreach command ends with an endfor on a separate line all by itself.

foreach i { a b c *.o [a-k]*[ch] } 
        echo $i 
endfor

format

This command formats diskettes, in the standard form (360K, or 720K) in either the A or B floppy drive. It does not touch hard-/ram-disks, no matter what arguments (illegal or not) you give it. Its valid arguments are either a, b, or both. The optional flag -2 implies double-sided formatting; otherwise the diskette is formatted single-sided.

format        # does nothing 
format b      # format the floppy in drive B, single-sided 
format -1 b   # same as format b 
format -2 a   # format the floppy in drive A, double-sided

If you issue the wrong command (e.g., format -2 a on a single-sided drive), you will hear a lot of grinding noises; a control-C will kill this, but not right away.

gem

The word gem is a prefix, like time is, to commands. This enables proper running via Guläm of most programs that use the desktop metaphor. It clears screen, turns cursor off, enables mouse and then executes the command, and after the command is finished it again clears screen, turns cursor on, disables mouse.

The time and gem prefixes mix in either order, and the command name will be searched for in the usual way.

We do not know, for sure, if all desktop/window/mouse oriented programs can be run properly with this command prefix. So experiment, and be ready to hit the reset button before using the prefix.

dvi is an example of a command that needs to be run with gem prefix. And you may be tempted to do the following.

alias dvi 'gem dvi'                   # recurses infinitely 
alias dzz dvi                         # dzz or whatever 
alias dvi 'gem dzz'                   # will work 
alias dvi 'gem c:\bin\dvi.prg'        # also will work

grep/egrep/fgrep

grep/egrep/fgrep re-pattern filenames

The grep command searches through a list of argument files for a specified string. Thus

grep lex[aw] e:\gulam\*.c

will print each line in the files that contains a substring matching lex[aw]. grep stands for “globally find regular expression matches and print”. grep and egrep are one and the same. The first argument to egrep is a regular expression, and the rest are expected to be file names. fgrep’s first argument is the as-is string to be searched for in the files. Because of the preprocessing done by Guläm, the as-is string for fgrep or the regular exp for egrep is generally enclosed in single-quotes.

gulam.g

Files with the .g extension are expected to contain Guläm commands; gulam.g is the name of the startup file. Guläm attempts to find this file in the current directory, and if found executes its contents. Here is an example file:

# bgn of my gulam.g

set prompt      '$ncmd $cwd gu > $u'
set histfile    e:\history.g
set baud_rate   9600
set sz_rs232_buffer     4096
set rgb '005-707-070-075-' # set the palette; note the trailing '-'
# the following sets tabs on Epson MX-80
set pr_bof '^Q033^QD^Q010^Q020^Q030^Q040^Q050^Q060^Q070^Q033^QC^Q102'
set pr_eof '^Q214'
set pr_eop '^Q214^Qn'
set pr_eol '^Qr^Qn'

#setenv PATH c:\bin,d:\bin,f:    # no trailing back slashes
#rehash
set path c:\bin,d:\bin,f:        # this is equiv to above 2 lines
setenv TEMP f:\
alias h   history
alias ll  ls -lF
alias p   more
alias rm rm -i # asks before deleting
alias ug 'ue e:\gulam\$1.c'
alias cg 'f:\cc.ttp -c -V -O -Ie:\gulam -Ie:\ue -DMWC e:\gulam\$1.c'
alias cpall 'cp e:\ue\*.o e:\gulam*.o f:\ '
alias bk 'cp e:\ue\*.[ch] e:\gulam\*.[ch] e:\gulam\mwc.s a:\ '
# end of my gulam.g

Gulam Variables and Environment

The following shell variables cause/control useful effects. The format of the explanation is ‘variable_name: default-value meaning’.

The following pr_XXX vars are relevant with print, and lpr commands. When set, these strings are sent to the printer :

Thus, to have a left margin of eight-spaces, just define pr_eol as QrQnQt. To turn condensed mode etc., just set pr_bof to the appropriate string after looking it up in the printer’s manual. See the section on strings for an explanation of Q.

HELP

The all-upper case name HELP in this manual stands for the key marked HELP on the Atari ST. Pressing this key, outside the ue, will show all the Guläm built-in commands, and a brief version of the hash table. Within ue, it can show the binding of an individual key, or produce a wall-chart of all bindings.

The shift-HELP key resets the special key table mapping that Gulam/uE use; after pressing shift-HELP the function keys, and arrow keys become equivalent to @, and the keypad will work as a typcial numerical keypad. To get back to the Gulam/uE key table, press L, which not only refreshes the display but also sets the key table.

help

Typing the letters help while outside ue, or in buffer guläm is equivalent to pressing HELP.

history

The history command lists the last N commands. Each command is preceded by its number; to suppress these numbers, supply the -h flag. The value N is obtained by $history. To change this N to, say, 30, do set history 30.

History Substitutions

Occurrences of the form !!, !number, !string refer to the text of previously issued commands. The text of these older commands itself does not contain ! unless it is part of a string argument. Each !! is replaced by the text of the immediately preceding command. Guläm consecutively numbers the commands that you have issued. (The current count can be seen in the shell variable named ncmd.) Each !n is replaced by the n-th old command. Each !str is a replaced by the most recent old command that begins with str.

The name completion feature works with history substitutions also. Pressing INSERT or ESC-ESC will bring the history-matched command and replace the current line in the buffer, which you can further edit.

$home also $HOME

The shell variable home is initially set to the full pathname of the directory from which Guläm was invoked. However, it can be set again with set command to whatever. The wiggle ~ in file names expands to $HOME.

The if stmt is similar to those in many programming languages. The Boolean expression of shell if stmts typically involves tests on file names and types. (See Expressions.) There is no then. Any remaining lexemes after the Boolean exp are ignored.

if {-d e:\gulam\lex} + 2 == 3 
        echo e:\gulam\lex is a dir 
ef -e e:\gulam\lex      # read ef as `else if' 
        echo e:\gulam\lex does exist 
ef 
        echo e:\gulam\lex does NOT exist 
endif

IO Redirection

Prefixing a file name f with > causes all standard output produced by that command to get deposited into file f. Similarly, <g will cause standard input to be taken from the file g rather than the key board. If you prefer, you may include white chars between the < (or > ) and the filename. If you have more than one <, or > in a command all but the last are ignored.

Note that because of TOS and compiler peculiarities, not all external commands will behave as above.

ls -l > lsout # get the ls -l output into file lsout
ls -l >> f1   # append the ls -l output to f1
ecmd '>blah'  # invoke ecmd and give it the arg >blah as is to it.

This command redefines microEmacs keybindings. To bind key with code 144 to function with hex-number 1d while you are in the regular buffer, do

Use -g for redefining the bindings of guläm buffer; -m for mini buffer. You can find the key codes and hex-numbers of functions in the wall-chart (shown below), which can be produced by pressing the HELP key, a B, and then a r (or g, or m). The key names, and function names will not appear unless a

set
gulam_help_file <filename>

was done earlier.

key-code in hex
|       function code in hex
|       |       key name (uekb ignores this)
|       |       |              function name  (uekb ignores this)
---------------------------------------------------------
081     5c      F1              kill-backward-word
082     5d      F2              kill-word
083     20      F3              kill-line
084     35      F4              copy-region-as-kill
085     51      F5              kill-buffer
086     50      F6              list-buffers
087     4e      F7              switch-to-buffer
088     3f      F8              write-file
089     3d      F9              find-file
08a     3e      F10             save-buffer
08b     14      HELP            help
08c     0d      UNDO            quick-exit
08d     62      INSERT          scroll-down
08e     61      HOME            scroll-up
0bb     23      UPARRO          previous-line
0bc     0f      DNARRO          gulam-forward-line
0bd     1a      LTARRO          backward-char
0be     1b      RTARRO          forward-char
140     30      C-@            set-mark-command
141     1e      C-A             beginning-of-line
142     1a      C-B             backward-char
143     06      C-C             switch-to-gulam-buffer
144     1d      C-D             delete-char
145     1f      C-E             goto-end-of-line
146     1b      C-F             forward-char
147     13      C-G             keyboard-quit
148     1c      C-H             backward-delete-char
149     11      TAB             goto-next-tab
14a     25      LFD             newline-and-indent
14b     20      C-K             kill-line
14c     19      C-L             redraw-display
14d     10      RET             gulam-do-newline
14e     0f      C-N             gulam-forward-line
14f     22      C-O             open-line
150     23      C-P             previous-line
151     33      C-Q             quoted-insert
152     2b      C-R             search-backward
153     2c      C-S             search-forward
154     34      C-T             transpose-chars
156     61      C-V             scroll-up
157     36      C-W             kill-region
159     3b      C-Y             yank
15a     0e      C-Z             temporary-exit
15f     14      C-_             help
029     6b      )               blink-matching-paren-hack
07d     6b      }              blink-matching-paren-hack
05d     6b      ]               blink-matching-paren-hack
0c0     0c      KLP             move-window-dn
0c1     0b      KRP             move-window-up
0c7     4a      KSLASH          split-window-vertically
0c2     49      KSTAR           delete-other-windows
0c5     45      KMINUS          previous-window
0c3     44      KPLUS           next-window
0c4     17      KENTER          call-last-kbd-macro
0c6     26      KDOT            goto-line
0b0     0a      K0              terminal-emulator
0b7     55      K7              beginning-of-buffer
0b8     32      K8              recenter
0b9     54      K9              end-of-buffer
0b4     5a      K4              backward-word
0b5     23      K5              previous-line
0b6     5e      K6              forward-word
0b1     1e      K1              beginning-of-line
0b2     0f      K2              gulam-forward-line
0b3     1f      K3              goto-end-of-line
541     09      C-X C-A         show-key-board-macro
542     50      C-X C-B         list-buffers
543     12      C-X C-C         save-buffers-kill-emacs
546     3d      C-X C-F         find-file
549     4d      C-X TAB         insert-buffer
54f     41      C-X C-O         delete-blank-lines
54e     0c      C-X C-N         move-window-dn
550     0b      C-X C-P         move-window-up
552     08      C-X C-R         read-file
553     3e      C-X C-S         save-buffer
556     3d      C-X C-V         find-file
557     3f      C-X C-W         write-file
558     42      C-X C-X         exchange-point-and-mark
55a     46      C-X C-Z         shrink-window
421     27      C-X !           execute-one-Gulam-command
421     07      C-X !           execute-buffer
43d     43      C-X =           what-cursor-position
428     15      C-X (           start-kbd-macro
429     16      C-X )           end-kbd-macro
431     49      C-X 1           delete-other-windows
432     4a      C-X 2           split-window-vertically
442     4e      C-X B           switch-to-buffer
445     17      C-X E           call-last-kbd-macro
446     18      C-X F           no-op
449     3c      C-X I           file-insert
44b     51      C-X K           kill-buffer
44e     44      C-X N           next-window
44f     44      C-X O           next-window
450     45      C-X P           previous-window
453     52      C-X S           save-some-buffers
45a     47      C-X Z           enlarge-window
348     5c      ESC C-H         kill-backward-word
221     07      ESC !           execute-buffer
22e     30      ESC .           set-mark-command
23e     54      ESC >           end-of-buffer
23c     55      ESC <           beginning-of-buffer
25b     56      ESC [           beginning-of-paragraph
25d     57      ESC ]           end-of-paragraph
225     2f      ESC %           query-replace
220     59      ESC SPC         just-one-space
242     5a      ESC B           backward-word
243     5b      ESC C           capitalize-word
244     5d      ESC D           kill-word
246     5e      ESC F           forward-word
247     06      ESC G           switch-to-gulam-buffer
24c     5f      ESC L           downcase-word
251     29      ESC Q           fill-paragraph
252     2b      ESC R           search-backward
253     2c      ESC S           search-forward
255     60      ESC U           upcase-word
256     62      ESC V           scroll-down
257     35      ESC W           copy-region-as-kill
27f     5c      ESC DEL         kill-backward-word
35b     05      ESC ESC         expand-name-gulam-style
344     63      ESC C-D         expand-names-and-show-them
346     04      ESC C-F         file-name
07f     1c      DEL             backward-delete-char
0ab     37      SHIFT-HELP      keys-reset
000     00      NUL             no-op
000     00      NUL             no-op
000     00      NUL             no-op
000     00      NUL             no-op
000     00      NUL             no-op
000     00      NUL             no-op
000     00      NUL             no-op
000     00      NUL             no-op
000     00      NUL             no-op
000     00      NUL             no-op

lpr

The command lpr prints its files as-is, with no processing at the end of lines.

ls [-lRLF] filenames

The ls (list files) command, with no arguments, prints the sorted list of names of the files in the current directory. It has a number of useful flag arguments, and can also be given the names of directories as arguments, in which case it lists the names of the files in these directories.

If no flags are given, ls prints only the filenames. The -L causes a full-length line for each file giving its attributes, size, creation date, and name. The -l (small el) is the same as -L except that the output is sorted by name. The -R will cause the subtrees of directories in the argument list of files to be traversed. The -F will append to each listed filename one char that indicates the type of that file: * if it is executable (i.e., has an extension of .prg, .tos, .ttp, or .g), a \ if its is a directory, a ’ ’ otherwise.

ls always (even if dir_cache is 1) updates the directory cache for the relevant directories.

mem

mem shows the list of free chunks of memory available. It does this by following lists starting at an (undocumented) TOS location (0x7e8e for ROMS dated 04221987, 56ec for older ROMS), Because of the way Guläm uses dynamically allocated memory, the size of the largest free chunk fluctuates both up and down as chunks get coalesced and split.

mem -a shows not only the free list, but also GEMDOS list of Malloc-ated chunks.

Metacharacter Expansion

The characters !$()[]><~*?, called meta characters, have special meaning to Guläm. If it is necessary to embed these characters in arguments to commands but without such special meaning, you must enclose the argument in single-quotes.

Arguments (to built-in or external commands) that contain meta chars are expanded as follows. The ! is expanded first; see History Substitution. After this, the meta chars $()[]~*? are expanded from left-to-right. See Dollar Substitution. The wiggle ~ stands for $HOME. The remaining meta chars ()[]*? are part of the fnmre – regular expressions for file names. Fnmre are slightly different from egrep’s Regular Expressions. An fnmre differs from re in (1) ‘.’ stands for itself; (2) ‘*’ is matches zero or more arbitrary characters. Occurrences of an fnmre, outside of strings, are replaced by the sorted blank-separated list of file names matching the fnmre; see also File Names.

mkdir

mv filenames target-dir
mv filename1 filename2

Moves files. In the first form, any number of files may be moveed into the destination directory; files in the target dir will have their original names. In the second form, only one file is moved, and the new one will be named filename2. On the Atari ST, moving files is accomplished by copying and then deleting the source file unless it is the second form and both are in the same directory.

mson/msoff

These enable/disable the mouse. Gulam/ue does not use the mouse; we intend to in a good way. Most GEM-based .prg programs use mouse, but do not set it up themselves. Some of these will hang if invoked from Guläm, which is no big deal; do mson and then try.

PATH

A comma-separated list (with no white chars) of directiries should be the value of this environment variable. This value is use by rehash command. rehash scans the files in each directory looking for executable files (by def, files with extensions of .prg, .tos. .ttp, or .g). The leaf names and full pathnames are entered into a hash table. Typing the help command (not the HELP key) will list the hash table in brief; which command lists it in full. Guläm does NOT auto rehash whenever PATH is changed (which I will change if a lot of you think it should).

setenv PATH c:,c:\bin,d:\mwc\bin

peekw/pokew

peekw and pokew are similar to their namesakes in BASIC. We use privileged mode to alter/access any arbitrary location. These commands expect their arguments to be hex numbers, so do not begin the numbers with 0x, or $. The pokew command should be used with care.

peekw 420      # shows you what is at word at 0x420 
pokew 420 123E # sets word at 0x420 to 0x123E

The primary use for these is to examine/alter the TOS variables. Refer to BIOS Hitch Hikers Guide, ST Internals, or some other documentation for a full list of these locations. Here are a few that I often found useful:

420 memvalid Normally contains 0x7520. If you then press reset the ST will do a ‘warm boot’ (which leaves most reset survivable RAM disks to be still alive). If you want to cause a cold boot, pokew this location to a zero. (The other way is to power cycle.)

42E and 0x430 phystop This pair of integers (a long) gives the address of top of RAM.

440 seekrate contains a code for the seek rate of floppies: 0 means 6 msec, 1 means 12 msec, 2 means 2 msec, and 3 means 3 msec.

444 fverify If pokew to zero, disk writes are not verified; any other value will.

popd

The popd command changes the shell’s working directory to the one on top of the directory stack. Also, sets cwd, and CWD.

The print command is used to prepare listings of the contents of files with headers giving the name of the file and the date and time at which the file was last modified.

printenv

$prompt

Guläm prompts for input with the contents of this variable. Set it with set command.

set prompt      '$ncmd $cwd gu > $u'

pushd

The pushd (push directory) command pushes the name of the current directory on to the internal stack, and cd’s to the directory given by the argument. You can later do a popd to return to the present current directory. The command pushd, without arguments, exchanges the working directory with the one on top of the stack.

pwd

This built-in command prints the full pathname of the current working directory.

Query Search/Replace

The built-in ue uses regular expression search and replace; see Regular Expressions. This function is normally bound to ESC-%. When you invoke it, it will ask you to type the search pattern, and then the replace pattern. It then enters the search/replace mode: finds the next (to the right, and below) occurrence of the search pattern, and awaits your response. You type

If you forget all this, type an arbitrary key and you will get the brief reminder:

<SP>replace, [.]rep-end, <DEL>don't, [!]repl rest, <ESC>quit

The only char that has a special meaning in the replace string is ‘&’; all other meta-chars stand literally for themselves. An ‘&’ stands for the substring that matched the whole regular expression. A ‘\n’, where n is a digit in 1 to 9, stands for the substring that matched the n-th parenthesized expression within the regular expression, with parenthesized expressions numbered in left-to-right order of their opening parentheses.

Be aware of a peculiarity of the search/replace: The ^ and $ of the regular expression match the positions just right of the dot, and just left of the dot. Thus, if you give a search string of ’^’, and replace string ’a’, and then issue a ’!’, you will be inserting ’a’ forever (until ue runs out of memory).

Regular Expressions

A regular expression is zero or more branches, separated by ‘|’. It matches anything that matches one of the branches.

A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.

A piece is an atom possibly followed by ‘*’, ‘+’, or ‘?’. An atom followed by ‘*’ matches a sequence of 0 or more matches of the atom. An atom followed by ‘+’ matches a sequence of 1 or more matches of the atom. An atom followed by ‘?’ matches a match of the atom, or the null string.

An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), ‘.’ (matching any single character), ‘^’ (matching the null string at the beginning of the input string), ‘$’ (matching the null string at the end of the input string), a ‘e’ followed by a single character (matching that character), or a single character with no other significance (matching that character).

A range is a sequence of characters enclosed in ‘[]’. It normally matches any single character from the sequence. If the sequence begins with ‘^’, it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by ‘-’, this is shorthand for the full list of ASCII characters between them (e.g. ‘[0-9]’ matches any decimal digit). To include a literal ‘]’ in the sequence, make it the first character (following a possible ‘^’). To include a literal ‘-’, make it the first or last character.

If a regular expression could match two different parts of the input string, it will match the one which begins earliest. If both begin in the same place but match different lengths, or match the same length in different ways, life gets messier, as follows.

In general, the possibilities in a list of branches are considered in left-to-right order, the possibilities for ‘*’, ‘+’, and ‘?’ are considered longest-first, nested constructs are considered from the outermost in, and concatenated constructs are considered leftmost-first. The match that will be chosen is the one that uses the earliest possibility in the first choice that has to be made. If there is more than one choice, the next will be made in the same manner (earliest possibility) subject to the decision on the first choice. And so forth.

For example, ‘(ab|a)b*c’ could match ‘abc’ in one of two ways. The first choice is between ‘ab’ and ‘a’; since ‘ab’ is earlier, and does lead to a successful overall match, it is chosen. Since the ‘b’ is already spoken for, the ‘b*’ must match its last possibility the empty string since it must respect the earlier choice.

In the particular case where no ‘|’s are present and there is only one ‘*’, ‘+’, or ‘?’, the net effect is that the longest possible match will be chosen. So ‘ab*’, presented with ‘xabbbby’, will match ‘abbbb’. Note that if ‘ab*’ is tried against ‘xabyabbbz’, it will match ‘ab’ just after ‘x’, due to the begins-earliest rule. (In effect, the decision on where to start the match is the first choice to be made, hence subsequent choices must respect it even if this leads them to less-preferred alternatives.)

ls *[sg]        # print file names ending in s or g
egrep '(MWC|MEGAMAX)' *.c       
egrep '^$' *.c  # print line numbers of empty lines
egrep 'aa*' *.c

rehash

ren

rm removes the named files. Most of us have the following aliases in our gulam.g files:

alias rm rm -i 
alias Rm rm

which queries you, for each file, before deleting it. We use Rm when we are really sure we want to delete the file(s). There is no special check to see if you typed rm *.* or rm *; both of these will clear your current directory.

rx/sx

These are built-in commands. rx receives a file from the remote system; and sx sends a file to the remote system using Xmodem protocol.

command opens/creates file fnm for writing. If the shell variable rx_remote_cmd is set, Guläm constructs a command for the remote system as $rx_remote_cmd fnm, and sends this command through the rs232 port, and then awaits the packets. For use with our 4xBSD Unix, we set this var to xm st. Unless the xm on the remote machine is of the quiet type (one that does not respond with, say, Xmodem: Ready to send...), setting rx_remote_cmd actually prolongs the first synchronization. If this var is unset, you should first switch to remote (say using te command), and issue the appropriate command to the remote, and then switch back to AtariST and give the rx fnm command.

is essentially similar. Guläm opens fnm for reading, sends $sx_remote_cmd fnm, if that var is set, and awaits the first sync. For our 4xBSD Unix, we set sx_remote_cmd to xm rt.

If sending/receiving binary files use xm rb or xm sb. Note that files received with Xmodem usually contain extraneous bytes at the very end of the file. With text files, you often see a bunch of Zs.

set

set [name value]

The built-in set command is used to assign new values to shell variables and to show the values of the current variables. The command without any arguments lists all the shell vars and their values. When arguments are present, second and subsequent words are processed as an expression yielding a value which is then assigned to the first argument. The unset command deletes a variable.

set i  {  $j > 10 } # sets i to 1 if $j is > 10; to 0 otherwise 
set x "hi there" 
set y $i + 4 @ 2     # @ stands for multiplication

setenv

Variables in the environment can be changed by using the setenv built-in command. The setenv command without args prints the values of all the variables in the environment.

source

The contents of file file-name are excuted by Guläm. Unless the file-name has an extension other than .g, use the simpler command file.g instead.

status

A command normally returns a status when it finishes. By convention a status of zero indicates that the command succeeded, and Guläm does not show this value. Commands may return non-zero status, whic is displayed, to indicate that some abnormal event has occurred. The shell variable status is set to the status returned by the last command.

Strings

Strings are the most common data type that shells deal with. In Guläm, unless otherwise stated, all operands are considered to be strings. There are a few occasions when it is necessary to suppress the typical string preprocessing such as meta-char expansion. Such strings are enclosed in single-quotes. A string enclosed in double quotes is dollar-, and meta-expanded, and then enclosed in double quotes. Try,

echo
*.c

and echo '*.c' in a directory that has a few files with the .c extension. Within a quoted-string, you can include control characters by inserting a Q (control-Q) followed by the octal ASCII code (always using 3 digits) of the character; see the gulam.g section for examples. In general, if you want to set a var to a string that contains control-chars, first write it out in the C language notation, and replace each back-slash with a control-Q.

te/teexit

te (also bound to Keypad-0) gets you into the built-in terminal emulator. If you have baud_rate set up properly (see gulam.g), the rs232 port is set to that speed, and you are switched to a fresh screen. Set sz_rs232_buffer to a large value if you encounter XON/XOFF problems too frequently. We have used the following TERMCAP and used vi, GNU-Emacs etc without any problems.

st|st25|atariST|520 or 1040, bw, std sys font, 25 lines, 80 col:
        :ae=Eba:al=EL:am:as=Ebc:
        :bl=^G:bs:
        :cd=EJ:ce=EK:cl=EHEJ:cm=EY%+ %+ :co#80:cr=^M:
        :dl=EM:do=EB:
        :ho=EH:
        :is=EvEe:
        :kd=274:kh=216:kl=275:kr=276:ku=273:
        :le=^H:li#25:
        :nd=EC:nl=^J:
        :pt:
        :se=Eq:so=Ep:sr=EI:
        :ta=^I:
        :up=EA:


ST|ST25|atariSTcolor|as above but with color for standout :
        :ae=Eba:al=EL:am:as=Ebc:
        :bl=^G:bs:
        :cm=EY%+ %+ :co#80:li#25:cr=^M:cd=EJ:ce=EK:cl=EHEJ:
        :dl=EM:do=^J:
        :ho=EH:
        :is=EvEe:
        :kd=274:kh=216:kl=275:kr=276:ku=273:
        :le=^H:
        :nd=EC:nl=^J:
        :pt:
        :so=Ec2Eb3:se=Ec0Eb3:sr:EI:
        :ta=^I:
        :up=EA:

sT|st50|AtariST emulating vt52, bw, 50 lines, 80 col:
        :ae=Eba:al=EL:am:as=Ebc:
        :bl=^G:bs:
        :cd=EJ:ce=EK:cl=EHEJ:cm=EY%+ %+ :co#80:cr=^M:
        :dl=EM:do=^J:
        :ho=EH:
        :is=EvEe:
        :kd=274:kh=216:kl=275:kr=276:ku=273:
        :le=^H:li#50:
        :nd=EC:nl=^J:
        :pt:
        :se=Eq:so=Ep:sr=EI:
        :ta=^I:
        :up=EA:

To return to the local mode after having done te, press UNDO. Then a Keypad-0 will take you back to remote with your remote screen in tact. After you are finally done with your remote system, press UNDO, and then issue a teexit to reclaim the 32k used for the extra screen.

Tenex File Name Completion

Tenex is widely considered to be the first OS to implement the completion of a file’s name given the first few chars of it. Experiment with the keys marked INSERT, TAB and CLR/HOME, while you are in mini. If you are in buffer guläm, use ESC-ESC (2 escapes). See File Names.

time

The word time when prefixed to a regular command, it prints the elapsed time after the command finishes. If you set variable named time to a non-zero value, each and every command, even if they are not prefixed with the word time, will be so timed.

time  ls -lF c:\        # See how long it takes 
set   time  1           # After this, all command will be timed until 
set   time 0            # you do this, or 
unset time              # this

If you set up aliases with time prefixes in them, watch out! The discussion under the section on Gem is applicable to time also.

touch

This command takes you into the built-in microEmacs editor. If no args are given, you will land in the guläm buffer, otherwise in the buffer of the last named file. The output of Guläm commands executed while you are within guläm is entered into that buffer; this, of course, consumes malloc-space. Meta-g brings you into guläm if you are in another buffer.

To examine the key bindings, press HELP-key first, and then a B while inside ue. To rebind them to suit your tastes, see kb. On the Atari ST, all the keys are bound (thoughtfully, I hope) to useful commands. F1 through F5 delete things; F6-F10 update files and buffers; Keypad keys cause harmless cursor motions; Keypad 0 (zero) switches you to the (remote computer hooked to the) rs232 port; to return to your local Atari, press UNDO. HELP is for (not much) help; UNDO will exit after saving files; the rest of the keys in that group move the cursor around.

The -r flag causes the buffers of the files following the -r to be marked as read-Only. You can still edit these buffers; but the read-Only mark causes ue to ask before writing to these files.

uekb

unalias

unalias [aliassed-name]

unset unsetenv

unset [var-name]
unsetenv [env-var]

variables

A variable name is any sequence of characters not containing delimiters. A Variable in Guläm holds a string as its value. Depending on the context this string is evaluated to yield a numeric value.

which

The which command displays the internal table of names of external commands, and the full pathnames of the files that contain them. If nothing gets displayed, either you did not do a rehash, did not setenv the PATH, or none of the directories in PATH had any executables.

while

The while built-in control construct is used in shell command scripts. Instead of echo and set in the body of the loop shown below, you can use other commands.

set i 10 
while  { $i >  0 } 
      echo $i 
      set i $i - 1 
endwhile

Variable Index

Command Index

About This Document

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

Button	Name	Go to	From 1.2.3 go to
[ << ]	FastBack	Beginning of this chapter or previous chapter	1
[ < ]	Back	Previous section in reading order	1.2.2
[ Up ]	Up	Up section	1.2
[ > ]	Forward	Next section in reading order	1.2.4
[ >> ]	FastForward	Next chapter	2
[Top]	Top	Cover (top) of document
[Contents]	Contents	Table of contents
[Index]	Index	Index
[ ? ]	About	About (help)

	Index Entry	Section

$
	`$cwd`	cp
	`$CWD`	cp
	`$end_style`	endfor
	`$home`	History Substitutions
	`$HOME`	History Substitutions
	`$prompt`	printenv

B
	`batch_echo`	Gulam Variables and Environment
	`batch_max_nesting`	Gulam Variables and Environment
	`baud_rate`	Gulam Variables and Environment

C
	`cwd`	Gulam Variables and Environment
	`CWD`	Gulam Variables and Environment

D
	`delay`	Gulam Variables and Environment
	`dir_cache`	Gulam Variables and Environment

G
	`ginprompt`	Gulam Variables and Environment
	`gulam_help_file`	Gulam Variables and Environment
	`gulam_help_file`	Gulam Variables and Environment

H
	`histfile`	Gulam Variables and Environment
	`home`	Gulam Variables and Environment
	`HOME`	Gulam Variables and Environment

M
	`mscursor`	Gulam Variables and Environment

N
	`ncmd`	Gulam Variables and Environment

P
	`path`	Gulam Variables and Environment
	`PATH`	Gulam Variables and Environment
	`PATH`	mson/msoff
	`prompt`	Gulam Variables and Environment
	`prompt_tail`	Gulam Variables and Environment
	`pr_bof`	Gulam Variables and Environment
	`pr_eof`	Gulam Variables and Environment
	`pr_eol`	Gulam Variables and Environment
	`pr_eop`	Gulam Variables and Environment

R
	`rgb`	Gulam Variables and Environment
	`RGB`	Gulam Variables and Environment
	`rx_remote_cmd`	Gulam Variables and Environment

S
	`semicolon_max`	Gulam Variables and Environment
	`status`	Gulam Variables and Environment
	`status`	source
	`sx_remote_cmd`	Gulam Variables and Environment
	`sz_rs232_buffer`	Gulam Variables and Environment

T
	`time`	Gulam Variables and Environment

V
	`verbosity`	Gulam Variables and Environment

	Index Entry	Section

A
	`alias`	Builtin Commands

B
	`builtins`	Glossary

C
	`cat`	alias
	`cd`	cat
	`chmod`	cd
	`cp`	chmod

D
	`date`	$cwd and $CWD
	`df`	date
	`dirc`	dm
	`dirs`	dir cache dirc
	`dir_cache`	dm
	`dm`	df

E
	`echo`	Dotg.g
	`ef`	echo
	`egrep`	ef
	`egrep`	gem
	`endfor`	endif
	`endif`	egrep
	`exit`	$env style

F
	`fg`	Expressions
	`fgrep`	gem
	`file-names`	fg
	`foreach`	Flags
	`format`	foreach

G
	`gem`	format
	`grep`	gem

H
	`help`	HELP
	`history`	help

I
	`if`	$home also $HOME

K
	`kb`	IO Redirection

L
	`lpr`	kb
	`ls`	lpr

M
	`mem`	ls
	`mkdir`	Metacharacter Expansion
	`msoff`	mv
	`mson`	mv
	`mv`	more

P
	`peekw`	PATH
	`pokew`	PATH
	`popd`	peekw/pokew
	`print`	popd
	`printenv`	print
	`pushd`	$prompt
	`pwd`	pushd

R
	`rehash`	Regular Expressions
	`ren`	rehash
	`rm`	ren
	`rx`	rm

S
	`set`	rx/sx
	`setenv`	set
	`source`	setenv
	`sx`	rm

T
	`te`	Strings
	`teexit`	Strings
	`time`	Tenex File Name Completion
	`touch`	time

U
	`ue`	touch
	`uekb`	ue
	`unalias`	uekb
	`unset`	unalias
	`unsetenv`	unalias

W
	`which`	variables
	`while`	which

A Reference Manual for

Guläm

Introduction